home *** CD-ROM | disk | FTP | other *** search
/ BCI NET 2 / BCI NET 2.iso / archives / programming / libraries / ptreplay420.lha / PTReplay / PTReplay.doc < prev    next >
Encoding:
Text File  |  1995-01-30  |  11.5 KB  |  471 lines
  1. -----------------------------------------------------------------------
  2.  
  3. PTReplay.library version 4.20 by Mattias Karlsson. © 1995 BetaSoft
  4. This version is FreeWare. You may use this library, and also copy it 
  5. further, provided that NO CHARGE is claimed. This message must always
  6. accompany any files in the PTReplay.library that is distributed.
  7.  
  8. -----------------------------------------------------------------------
  9.  
  10. This is ptreplay.library version 4. It is a standard Amiga shared library,
  11. capable of replaying ProTracker modules.
  12. The replay routines are 99% system-friendly¹, and use CIA timing, which
  13. gives a smoother replaying.
  14.  
  15. Use this library as you would use any normal Amiga library. Included in
  16. this package is include files for Assembler and C. 
  17.  
  18. I wrote this library because I was unable to find a _good_ and system-
  19. friendly replay routine for ProTracker. I based this loosely on the 
  20. example sources that accompany ProTracker, but these were pretty badly
  21. written, and sparsly commented, and the CIA routines did never work on
  22. my machine. A job worth doing well is worth doing yourself, I though
  23. and went to work. This is what emerged, a small library. Notice that it
  24. is not even 7k, and still contains all needed to play good music.
  25.  
  26. NOTE: All library functions are safe to call with a NULL parameter.
  27.  
  28. If you want to contact me for any reason, you can write to:
  29.  
  30.   UUCP:  betasoft@algonet.se     *********** NOTE new adress ***********
  31.   FIDO:  Mattias Karlsson@2:205/425.0
  32.  
  33. SNAIL: BetaSoft
  34.        Mattias Karlsson
  35.        Slöjdgatan 6
  36.        S-930 61  Bastuträsk
  37.        SWEDEN
  38.  
  39. Changes from 4.18 to 4.20
  40. -------------------------
  41.  
  42. * Fixed a bug which turn on the filter instead of turning it off.
  43.  
  44. * It now checks the file to ensure that it realy is a module before
  45.   it is loaded.
  46.  
  47. Changes from 4.16 to 4.18
  48. -------------------------
  49.  
  50. * Modules created by SetupMod whould clear the 4 bytes behind the module,
  51.   this is now fixed.
  52.  
  53. * Doing a position jump now also trigger a module restart signal.
  54.  
  55. These are features I would like to add:
  56. --------------------------------------
  57. * Various small enhancements and speed increases.
  58.  
  59. * spliting a module intro several blocks (Currently it loads into one block).
  60.  
  61. * Temporary storing of modules in fastmem.
  62.  
  63. ---------------------------------------------------------------------------------
  64. ¹ 99% because the library doesn't reserve the sound channels it uses. If
  65.   you want this feature in your program, you'll have to do it yourself,
  66.   using audio.device².
  67.  
  68. ² See 'Rom Kernel Reference Manual: Devices' for information on how to use
  69.   audio.device and reserve sound channels.
  70.  
  71. *********************************************************************************
  72.  
  73. NAME
  74.     PTLoadModule
  75.  
  76. SYNOPSIS
  77.     module = PTLoadModule(name)
  78.        D0                 A0
  79.  
  80.     struct module *PTLoadModule(STRPTR);
  81.  
  82. FUNCTION
  83.     Attempts to load the module named.
  84.  
  85. INPUTS
  86.     name - pointer to null-terminated string containing name of module.
  87.  
  88. RESULT
  89.     module - pointer to module control structure or NULL if failed.
  90.  
  91. SEE ALSO
  92.     PTSetupMod
  93.  
  94. -----------------------------------------------------------------------------
  95.  
  96. NAME
  97.     PTUnloadModule
  98.  
  99. SYNOPSIS
  100.     PTUnloadModule(module)
  101.                    A0
  102.  
  103.     void PTUnloadModule(struct Module *);
  104.  
  105. FUNCTION
  106.     Frees all memory used by the module.
  107.  
  108. INPUTS
  109.     module - pointer to module control structure.
  110.  
  111. BUGS
  112.     Does not check that module is stopped. If you call this function on
  113.     a module that is playing, you _will_ cause a System Failure. You
  114.     have been warned.
  115.  
  116. -----------------------------------------------------------------------------
  117.  
  118. NAME
  119.     PTPlay
  120.  
  121. SYNOPSIS
  122.     PTPlay(module)
  123.            A0
  124.  
  125.     void PTPlay(struct Module *);
  126.  
  127. FUNCTION
  128.     Start playing the module from the beginning. If this module already
  129.     was playing, it starts over from the beginning.
  130.  
  131. INPUTS
  132.     module - pointer to module control structure.
  133.  
  134. BUGS
  135.     It is not yet supported to call this function while another module
  136.     is playing.
  137.  
  138. -----------------------------------------------------------------------------
  139.  
  140. NAME
  141.     PTStop
  142.      
  143. SYNOPSIS
  144.     PTStop(module)
  145.            A0
  146.  
  147.     void PTStop(struct Module *);
  148.  
  149. FUNCTION
  150.     Stop playing the indicated module. If it wasn't playing, nothing
  151.     happens.
  152.      
  153. INPUTS
  154.     module - pointer to module control structure.
  155.  
  156. -----------------------------------------------------------------------------
  157.  
  158. NAME
  159.     PTPause
  160.      
  161. SYNOPSIS
  162.     PTPause(module)
  163.             A0
  164.  
  165.     void PTPause(struct Module *);
  166.  
  167. FUNCTION
  168.     Pause this module, remembering the position so that you can restart
  169.     it later. All sound is turned off.
  170.      
  171. INPUTS
  172.     module - pointer to module control structure.
  173.  
  174. SEE ALSO
  175.     PTResume
  176.  
  177. -----------------------------------------------------------------------------
  178.  
  179. NAME
  180.     PTResume
  181.      
  182. SYNOPSIS
  183.     PTResume(module)
  184.              A0
  185.  
  186.     void PTResume(struct Module *);
  187.  
  188. FUNCTION
  189.     Resume playing this module, after it was paused. If it was not paused
  190.     then nothing happens.
  191.  
  192. INPUTS
  193.     module - pointer to module control structure.
  194.  
  195. SEE ALSO
  196.     PTPause
  197.  
  198. -----------------------------------------------------------------------------
  199.  
  200. NAME
  201.     PTFade (V2)
  202.  
  203. SYNOPSIS
  204.     PTFade(module,speed)
  205.            A0     D0
  206.  
  207.     void PTFade(struct Module *, UBYTE);
  208.  
  209. FUNCTION
  210.     This function does smooth vol slidedown until volume reaches zero, then
  211.     the module is stoped and the function returns. The speed is given
  212.     in the number of "vblanks" (ie CIA timeouts because it uses CIA timing
  213.     instead of vblank timing) between each step.
  214.  
  215. INPUTS
  216.     module - module that is to be stoped.
  217.     speed - fading speed.
  218.  
  219. SEE ALSO
  220.     PTStartFade
  221.  
  222. -----------------------------------------------------------------------------
  223.  
  224. NAME
  225.     PTSetVolume (V3)
  226.  
  227. SYNOPSIS
  228.     PTSetVolume(module,volume)
  229.                 A0     D0
  230.  
  231.     void PTSetVolume(struct Module, UBYTE);
  232.  
  233. FUNCTION
  234.     Change the volume of a module while it is playing.
  235.  
  236. INPUTS
  237.     module - pointer to module.
  238.     speed  - new volume  0-64 ($00-$40)
  239.  
  240. -----------------------------------------------------------------------------
  241.  
  242. NAME
  243.     PTSongPos (V4)
  244.  
  245. SYNOPSIS
  246.     Pos=PTSongPos(module);
  247.     d0            A0
  248.  
  249.     UBYTE PTSongPos(struct Module *)
  250.  
  251. FUNCTION
  252.     This function returns the position the module is curently playing.
  253.  
  254. INPUTS
  255.     module - pointer to a module that is playing.
  256.  
  257. RESULTS
  258.     Pos - What position that is playing (0 - (Length-1) ) or 0 if not playing
  259.  
  260. -----------------------------------------------------------------------------
  261.  
  262. NAME
  263.     PTSongLen (V4)
  264.  
  265. SYNOPSIS
  266.     Len=PTSongLen(module)
  267.     d0            a0
  268.  
  269.     UBYTE PTSongLen(struct Module *);
  270.  
  271. FUNCTION
  272.     This funktion returns the length of the module is positions. This is the
  273.     same value as Length in ProTracker and means that it will play until
  274.     position Len-1.
  275.  
  276. INPUTS
  277.     module - The module whos length you which to now.
  278.  
  279. RESULTS
  280.     Len - Number of positions in module
  281.  
  282. -----------------------------------------------------------------------------
  283.  
  284. NAME
  285.     PTSongPattern (V4)
  286.  
  287. SYNOPSIS
  288.     PatNum=PTSongPattern(module, pos)
  289.     D0                   A0      D0
  290.  
  291.     UBYTE PTSongPattern(struct Module *,UWORD);
  292.  
  293. FUNCTION
  294.     Returns the pattern number at a given position.
  295.  
  296. INPUTS
  297.     Module - The module you want to examine
  298.     Pos - The position (0-127) you want to examine.
  299.  
  300. RESULTS
  301.     PatNum - A number (0-127) telling you which pattern is to be played.
  302.  
  303. -----------------------------------------------------------------------------
  304.  
  305. NAME
  306.     PTPatternPos (V4)
  307.  
  308. SYNOPSIS
  309.     Row=PTPatternPos(module)
  310.     D0               A0
  311.  
  312.     UBYTE PTPatternPos(struct Module *);
  313.  
  314. FUNCTION
  315.     Returns the row in the pattern that it is currently being played.
  316.  
  317. INPUTS
  318.     module - A module that is currently being played.
  319.  
  320. RESULTS
  321.     Row - The row (0-63 $00-$40) that is being played.
  322.  
  323. -----------------------------------------------------------------------------
  324.  
  325. NAME
  326.     PTPatternData (V4)
  327.  
  328. SYNOPSIS
  329.     RowData=PTPatternData(Module, PatternNum, RowNum)
  330.     D0                    A0      D0          D1
  331.  
  332.     APTR PTPatternData(struct Module *, UBYTE, UBYTE);
  333.  
  334. FUNCTION
  335.     This function returns a pointer to the given row in the a specified
  336.     pattern.
  337.  
  338. INPUTS
  339.     Module - Pointer to the module you which to examine.
  340.     PatternNum - The pattern (0-127) you want to examine.
  341.     RowNum - And finaly the which row (0-63) to examine.
  342.  
  343. RESULTS
  344.     RowData - An adresspointer to the given position
  345.  
  346. -----------------------------------------------------------------------------
  347.  
  348. NAME
  349.     PTInstallBits (V4)
  350.  
  351. SYNOPSIS
  352.     PTInstallBits(Module, Restart, Pos, Row, Fade);
  353.                   A0      D0       D1   D2   D3
  354.  
  355.     void PTInstallBits(struct Module *, BYTE, BYTE, BYTE, BYTE);
  356.  
  357. FUNCTION
  358.     This function is used to inform ptreplay which signals to send to this
  359.     task at the given positions. Currently it can only be set up to signal
  360.     one task/module (the one calling this function) this may however change
  361.     in future. A signalbit of -1 tells ptreplay not to signal you at that
  362.     specific location.
  363.  
  364. EXAMPLE
  365.     /* This will set signalbit 4 when the module restarts from the beginning */
  366.     PTInstallBits(Module, 4, -1, -1, -1);
  367.  
  368.     /* This will set signal 0 when startfade has stopped the module */
  369.     PTInstallBits(Module, -1, 1, -1, 0);
  370.  
  371. INPUTS
  372.     Module - module to use the given signals
  373.     Restart - Bit to set when a module restarts from beginning or -1 for no
  374.         signal
  375.     Pos - Bit to set when moving to next position or -1 for no signal
  376.     Row - Bit to set when moving to next row in pattern or -1 for no signal
  377.     Fade - Bit to set when PTStartFade is done and have stoped module or -1
  378.         for no signal.
  379.  
  380. SEE ALSO
  381.     PTStartFade
  382.  
  383. -----------------------------------------------------------------------------
  384.  
  385. NAME
  386.     PTSetupMod (V4)
  387.  
  388.     Module = PTSetupMod(LoadedMod);
  389.     D0                  A0
  390.  
  391.     struct Module *PTSetupMod(APTR);
  392.  
  393. FUNCTION
  394.     This function will allocate a module control structure and intilize it
  395.     using an already loaded module file, in order to use in with ptreplay.
  396.  
  397. EXAMPLE
  398.     /* This routine will do the same thing as PTLoadMod */
  399.     BPTR File;
  400.     APTR Mod;
  401.     int Len;
  402.     struct Module *Module;
  403.  
  404.     File=Open("mod.module",MODE_OLDFILE))
  405.     Seek(File, 0l, OFFSET_END);
  406.     Len=Seek(File, 0l, OFFSET_BEGINNING);
  407.  
  408.     Mod=AllocMem(Len, MEMF_CHIP);
  409.     Read(File, Mod, Len);
  410.     Close(File);
  411.     Module=PTSetupMod(Mod);
  412.  
  413. NOTE
  414.     1. The module MUST already be located in chip mem.
  415.     2. The module MUST be valid while the module is goint to be used.
  416.     Both may change in future.
  417.  
  418. INPUTS
  419.     LoadedMod - An pointer to an already loaded module.
  420.  
  421. RESULTS
  422.     Module - A module structure to be used 
  423.  
  424. SEE ALSO
  425.     PTFreeMod
  426.  
  427. -----------------------------------------------------------------------------
  428.  
  429. NAME
  430.     PTFreeMod (V4)
  431.  
  432. SYNOPSIS
  433.     PTFreeMod(Module)
  434.               A0
  435.  
  436.     void PTFreeMod(struct Module *);
  437.  
  438. FUNCTION
  439.     This function will free all memory allocated by the PTSetupMod function.
  440.  
  441. INPUTS
  442.     Module - a module returned by PTSetupMod().
  443.  
  444. SEE ALSO
  445.     PTSetupMod
  446.  
  447. -----------------------------------------------------------------------------
  448.  
  449. NAME
  450.     PTStartFade (V4)
  451.  
  452. SYNOPSIS
  453.     PTStartFade(Module, Speed)
  454.                 A0      D0
  455.  
  456.     void PTStartFade(struct Module *, UBYTE);
  457.  
  458. FUNCTION
  459.     This function will also do a smooth volume slidedown in the same way
  460.     as PTFade does but it returns as soon as the fading has started instead
  461.     of when it is done. Currently the only way to notice when the module
  462.     is stoped is to setup a Fade bit using PTInstallBits and check for that
  463.     bit.
  464.  
  465. INPUTS
  466.     Module - Module to be stoped.
  467.     Speed - fading speed.
  468.  
  469. SEE ALSO
  470.     PTFade, PTInstallBits
  471.